home *** CD-ROM | disk | FTP | other *** search
/ IRIX 6.2 Development Libraries / SGI IRIX 6.2 Development Libraries.iso / dist / complib.idb / usr / share / catman / p_man / cat3 / complib / strsna.z / strsna
Text File  |  1996-03-14  |  9KB  |  265 lines
  1.  
  2.  
  3.  
  4. SSSSTTTTRRRRSSSSNNNNAAAA((((3333FFFF))))                                                          SSSSTTTTRRRRSSSSNNNNAAAA((((3333FFFF))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      STRSNA - estimate reciprocal condition numbers for specified eigenvalues
  10.      and/or right eigenvectors of a real upper quasi-triangular matrix T (or
  11.      of any matrix Q*T*Q**T with Q orthogonal)
  12.  
  13. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  14.      SUBROUTINE STRSNA( JOB, HOWMNY, SELECT, N, T, LDT, VL, LDVL, VR, LDVR, S,
  15.                         SEP, MM, M, WORK, LDWORK, IWORK, INFO )
  16.  
  17.          CHARACTER      HOWMNY, JOB
  18.  
  19.          INTEGER        INFO, LDT, LDVL, LDVR, LDWORK, M, MM, N
  20.  
  21.          LOGICAL        SELECT( * )
  22.  
  23.          INTEGER        IWORK( * )
  24.  
  25.          REAL           S( * ), SEP( * ), T( LDT, * ), VL( LDVL, * ), VR(
  26.                         LDVR, * ), WORK( LDWORK, * )
  27.  
  28. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  29.      STRSNA estimates reciprocal condition numbers for specified eigenvalues
  30.      and/or right eigenvectors of a real upper quasi-triangular matrix T (or
  31.      of any matrix Q*T*Q**T with Q orthogonal).
  32.  
  33.      T must be in Schur canonical form (as returned by SHSEQR), that is, block
  34.      upper triangular with 1-by-1 and 2-by-2 diagonal blocks; each 2-by-2
  35.      diagonal block has its diagonal elements equal and its off-diagonal
  36.      elements of opposite sign.
  37.  
  38.  
  39. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  40.      JOB     (input) CHARACTER*1
  41.              Specifies whether condition numbers are required for eigenvalues
  42.              (S) or eigenvectors (SEP):
  43.              = 'E': for eigenvalues only (S);
  44.              = 'V': for eigenvectors only (SEP);
  45.              = 'B': for both eigenvalues and eigenvectors (S and SEP).
  46.  
  47.      HOWMNY  (input) CHARACTER*1
  48.              = 'A': compute condition numbers for all eigenpairs;
  49.              = 'S': compute condition numbers for selected eigenpairs
  50.              specified by the array SELECT.
  51.  
  52.      SELECT  (input) LOGICAL array, dimension (N)
  53.              If HOWMNY = 'S', SELECT specifies the eigenpairs for which
  54.              condition numbers are required. To select condition numbers for
  55.              the eigenpair corresponding to a real eigenvalue w(j), SELECT(j)
  56.              must be set to .TRUE.. To select condition numbers corresponding
  57.              to a complex conjugate pair of eigenvalues w(j) and w(j+1),
  58.              either SELECT(j) or SELECT(j+1) or both, must be set to .TRUE..
  59.              If HOWMNY = 'A', SELECT is not referenced.
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. SSSSTTTTRRRRSSSSNNNNAAAA((((3333FFFF))))                                                          SSSSTTTTRRRRSSSSNNNNAAAA((((3333FFFF))))
  71.  
  72.  
  73.  
  74.      N       (input) INTEGER
  75.              The order of the matrix T. N >= 0.
  76.  
  77.      T       (input) REAL array, dimension (LDT,N)
  78.              The upper quasi-triangular matrix T, in Schur canonical form.
  79.  
  80.      LDT     (input) INTEGER
  81.              The leading dimension of the array T. LDT >= max(1,N).
  82.  
  83.      VL      (input) REAL array, dimension (LDVL,M)
  84.              If JOB = 'E' or 'B', VL must contain left eigenvectors of T (or
  85.              of any Q*T*Q**T with Q orthogonal), corresponding to the
  86.              eigenpairs specified by HOWMNY and SELECT. The eigenvectors must
  87.              be stored in consecutive columns of VL, as returned by SHSEIN or
  88.              STREVC.  If JOB = 'V', VL is not referenced.
  89.  
  90.      LDVL    (input) INTEGER
  91.              The leading dimension of the array VL.  LDVL >= 1; and if JOB =
  92.              'E' or 'B', LDVL >= N.
  93.  
  94.      VR      (input) REAL array, dimension (LDVR,M)
  95.              If JOB = 'E' or 'B', VR must contain right eigenvectors of T (or
  96.              of any Q*T*Q**T with Q orthogonal), corresponding to the
  97.              eigenpairs specified by HOWMNY and SELECT. The eigenvectors must
  98.              be stored in consecutive columns of VR, as returned by SHSEIN or
  99.              STREVC.  If JOB = 'V', VR is not referenced.
  100.  
  101.      LDVR    (input) INTEGER
  102.              The leading dimension of the array VR.  LDVR >= 1; and if JOB =
  103.              'E' or 'B', LDVR >= N.
  104.  
  105.      S       (output) REAL array, dimension (MM)
  106.              If JOB = 'E' or 'B', the reciprocal condition numbers of the
  107.              selected eigenvalues, stored in consecutive elements of the
  108.              array. For a complex conjugate pair of eigenvalues two
  109.              consecutive elements of S are set to the same value. Thus S(j),
  110.              SEP(j), and the j-th columns of VL and VR all correspond to the
  111.              same eigenpair (but not in general the j-th eigenpair, unless all
  112.              eigenpairs are selected).  If JOB = 'V', S is not referenced.
  113.  
  114.      SEP     (output) REAL array, dimension (MM)
  115.              If JOB = 'V' or 'B', the estimated reciprocal condition numbers
  116.              of the selected eigenvectors, stored in consecutive elements of
  117.              the array. For a complex eigenvector two consecutive elements of
  118.              SEP are set to the same value. If the eigenvalues cannot be
  119.              reordered to compute SEP(j), SEP(j) is set to 0; this can only
  120.              occur when the true value would be very small anyway.  If JOB =
  121.              'E', SEP is not referenced.
  122.  
  123.      MM      (input) INTEGER
  124.              The number of elements in the arrays S (if JOB = 'E' or 'B')
  125.              and/or SEP (if JOB = 'V' or 'B'). MM >= M.
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. SSSSTTTTRRRRSSSSNNNNAAAA((((3333FFFF))))                                                          SSSSTTTTRRRRSSSSNNNNAAAA((((3333FFFF))))
  137.  
  138.  
  139.  
  140.      M       (output) INTEGER
  141.              The number of elements of the arrays S and/or SEP actually used
  142.              to store the estimated condition numbers.  If HOWMNY = 'A', M is
  143.              set to N.
  144.  
  145.      WORK    (workspace) REAL array, dimension (LDWORK,N+1)
  146.              If JOB = 'E', WORK is not referenced.
  147.  
  148.      LDWORK  (input) INTEGER
  149.              The leading dimension of the array WORK.  LDWORK >= 1; and if JOB
  150.              = 'V' or 'B', LDWORK >= N.
  151.  
  152.      IWORK   (workspace) INTEGER array, dimension (N)
  153.              If JOB = 'E', IWORK is not referenced.
  154.  
  155.      INFO    (output) INTEGER
  156.              = 0: successful exit
  157.              < 0: if INFO = -i, the i-th argument had an illegal value
  158.  
  159. FFFFUUUURRRRTTTTHHHHEEEERRRR DDDDEEEETTTTAAAAIIIILLLLSSSS
  160.      The reciprocal of the condition number of an eigenvalue lambda is defined
  161.      as
  162.  
  163.              S(lambda) = |v'*u| / (norm(u)*norm(v))
  164.  
  165.      where u and v are the right and left eigenvectors of T corresponding to
  166.      lambda; v' denotes the conjugate-transpose of v, and norm(u) denotes the
  167.      Euclidean norm. These reciprocal condition numbers always lie between
  168.      zero (very badly conditioned) and one (very well conditioned). If n = 1,
  169.      S(lambda) is defined to be 1.
  170.  
  171.      An approximate error bound for a computed eigenvalue W(i) is given by
  172.  
  173.                          EPS * norm(T) / S(i)
  174.  
  175.      where EPS is the machine precision.
  176.  
  177.      The reciprocal of the condition number of the right eigenvector u
  178.      corresponding to lambda is defined as follows. Suppose
  179.  
  180.                  T = ( lambda  c  )
  181.                      (   0    T22 )
  182.  
  183.      Then the reciprocal condition number is
  184.  
  185.              SEP( lambda, T22 ) = sigma-min( T22 - lambda*I )
  186.  
  187.      where sigma-min denotes the smallest singular value. We approximate the
  188.      smallest singular value by the reciprocal of an estimate of the one-norm
  189.      of the inverse of T22 - lambda*I. If n = 1, SEP(1) is defined to be
  190.      abs(T(1,1)).
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. SSSSTTTTRRRRSSSSNNNNAAAA((((3333FFFF))))                                                          SSSSTTTTRRRRSSSSNNNNAAAA((((3333FFFF))))
  203.  
  204.  
  205.  
  206.      An approximate error bound for a computed right eigenvector VR(i) is
  207.      given by
  208.  
  209.                          EPS * norm(T) / SEP(i)
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.